Loading TOC...
Matches for cat:rest-api (cat:rest-api) have been highlighted. remove

MarkLogic Server 11.0 Product Documentation
PUT /manage/v2/databases/{id|name}/partitions/{name}

Summary

Invoke an operation on a partition, such as resizing the partition or transferring or migrating the partition to a different database.

URL Parameters
format The format of the data in the request body. Allowed values: json, or xml. Use this parameter to override the Content-type header.
Request Headers
Accept The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header. Supported values: application/xml, application/json.

Response

The response depends on the requested operation. The synchronous transfer operation returns status code 200 (OK) upon success. The asynchronous resize and migrate operations return status code 202 (Accepted) and a response body that includes a link to the process status view for the affected resource. If the payload is malformed, a status code of 400 (Bad Request) is returned. A status code of 401 (Unauthorized) is returned if the user does not have the necessary privileges.

Required Privileges

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage-admin

Usage Notes

The operation performed by the request is determined by the wrapper element name in XML or the value of the operation key in JSON. The following operations are supported: resize, transfer, and migrate.

For details on the operations, see tieredstorage:partition-resize, tieredstorage:partition-migrate, tieredstorage:partition-transfer, and Common Forest and Partition Operations in the Administrator's Guide.

This method can be either synchronous or asynchronous, depending on the type of operation: Resize and migrate are asynchronous operations, transfer is a synchronous operation.

Asynchronous operations return status 202 (Accepted) and the response Location header contains a reference to a ticket you can use to check on the status and outcome of the operation using GET /manage/v2/tickets/{tid}. Synchronous operations return status 204 (No Content).

For the transfer operation, the input data structure contains a destination-database. For details, see the examples. Before transferring a range partition from one database to another, you must configure the destination database to have a matching range policy.

For the migrate operation, the request body must be a structure similar to that for resize, but omitting forests-per-host. You must include at least the host list. All other fields are optional, except that JSON input must include operation.

For the resize operation, the request body must have the following structure. You must include the host list and forests-per-host. All other fields are optional, except that JSON input must include operation.

operation

forests-per-host

Number of forests to distribute per host.

hosts

A list of hosts.

This is a complex structure with the following children:

host

A host name or id.

data-directory

The optional public directory for forests.

large-data-directory

The optional directory for large objects in a forest.

fast-data-directory

The optional smaller but faster directory for forests.

options

A list of options.

This is a complex structure with the following children:

option

An option.

Example



$ cat partition-resize.xml
==> 
<resize xmlns="http://marklogic.com/manage">
  <forests-per-host>2</forests-per-host>
  <hosts>
    <host>host-1</host>
    <host>host-2</host>
  </hosts>
</resize>

The equivalent JSON configuration:
$ cat partition-resize.json
==> 
{
  "operation": "resize",
  "forests-per-host": 2,
  "host": [ "host-1", "host-2" ]
}

$ curl --anyauth --user user:password -X PUT -d @./partition-resize.xml \
    -i -H "Content-type: application/xml" \
    http://localhost:8002/manage/v2/databases/example-db/partitions/2011

==> The range partition named "2011" is resized such that it has 2 forests on
    each host. New forests are created as needed. Since the operation
    is asynchronous, MarkLogic Server responds with ticket information
    similar to the following:

HTTP/1.1 202 Accepted
Content-type: application/xml
Cache-Control: no-cache
Expires: -1
Location: /manage/v2/tickets/14991169073676404304?view=process-status
Server: MarkLogic
Content-Length: 246
Connection: Keep-Alive
Keep-Alive: timeout=5

<resize xmlns="http://marklogic.com/manage">
  <link>
    <kindref>process-status</kindref>
    <uriref>/manage/v2/tickets/14991169073676404304?view=process-status</uriref>
  </link>
  <message>Monitor operation progress by viewing ticket</message>
</resize>

Example


$ cat partition-transfer.xml
==> 
<transfer xmlns="http://marklogic.com/manage">
  <destination-database>destination-db</destination-database>
</transfer>

$ cat partition-transfer.json
==> 
{
  "operation": "transfer",
  "destination-database": "destination-db"
}

$ curl --anyauth --user user:password -X PUT -d @./partition-transfer.xml \
    -i -H "Content-type: application/xml" \
    http://localhost:8002/manage/v2/databases/source-db/partitions/2011

==> The partition named "2011" is transferred from source-db to
    destination-db. New forests are created in destination-db. The
    forests in the partition in destination-db are detached from the
    database. This is a synchronous operation. MarkLogic Server responds 
    with headers similar to the following:

HTTP/1.1 204 No Content
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

Example


$ cat partition-migrate.xml
==> 
<migrate xmlns="http://marklogic.com/manage">
  <hosts>
    <host>dest-host-1</host>
    <host>dest-host-2</host>
  </hosts>
</migrate>

The equivalent JSON configuration:
$ cat partition-migrate.json
==> 
{
  "operation": "migrate",
  "host": [ "dest-host-1", "dest-host-2" ]
}

$ curl --anyauth --user user:password -X PUT -d @./partition-migrate.xml \
    -i -H "Content-type: application/xml" \
    http://localhost:8002/manage/v2/databases/example-db/partitions/2011

==> The range partition named "2011" is migrated to the hosts dest-host-1
    and dest-host-2. This is an asynchronous operation. MarkLogic Server
    Server responds with ticket information similar to the following:

HTTP/1.1 202 Accepted
Content-type: application/xml
Cache-Control: no-cache
Expires: -1
Location: /manage/v2/tickets/14991169073676404304?view=process-status
Server: MarkLogic
Content-Length: 246
Connection: Keep-Alive
Keep-Alive: timeout=5

<migrate xmlns="http://marklogic.com/manage">
  <link>
    <kindref>process-status</kindref>
    <uriref>/manage/v2/tickets/14991169073676404304?view=process-status</uriref>
  </link>
  <message>Monitor operation progress by viewing ticket</message>
</migrate>

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.